<HTML><HEAD><TITLE>analyse(+File)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(mode_analyser)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>analyse(+File)</H1>
Compile a file, inserting invocation mode analysis 
   instrumentation for each predicate definition.
<DL>
<DT><EM>File</EM></DT>
<DD>Atom or string
</DD>
</DL>
<H2>Description</H2>
<P>    
   The mode analyser is a variant of the ECLiPSe that inserts 
   instrumentation into the clause definitions of predicates
   (defined in the named file) during compilation in order to record mode 
   usage of each predicate argument. The code is then run as many times 
   as is necessary to capture the most common invocations of each 
   predicate undergoing analysis. Finally, the results are analysed, 
   using <TT>mode_analyser:result/0</TT>, to produce suggested mode/1 
   directives for each predicate.
   </P><P>
   The mode/1 directive informs the compiler that the arguments of the 
   specified predicate will always have the corresponding form when the 
   predicate is called.  The compiler utilises this information during 
   compilation of the predicate in order to generate more compact and/or 
   faster code. Specifying the mode of a predicate that has already been 
   compiled has no effect, unless it is recompiled. If the specified 
   procedure does not exist, a local undefined procedure is created.
   </P><P>
   NOTE: It is imperative to understand that the results of mode analysis 
   are merely suggestions for the invocation modes of a predicate based on 
   runtime information. If there are potential predicate invocation modes 
   that were not exercised during runtime, the tool is unable to account 
   for them in its analysis. For the mode specifier '-' the mode analyser
   does not determine whether the variable occurs in any other argument
   (i.e. is aliased), this must be manually verified. 
   In summary, the programmer must verify that the suggested modes are correct 
   before using the directive in the code.  If the instantiation of the 
   predicate call violates its mode declaration, no exception is raised and 
   its behaviour is undefined.
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Resatisfiable</H3>
no
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>File is not an atom or string
</DL>
<H2>Examples</H2>
<PRE>
   [eclipse 1]: mode_analyser:analyse('queens_gfc.pl').
   queens_gfc.pl compiled traceable 13920 bytes in 0.10 seconds

   Yes (0.10s cpu)</PRE>
<H2>See Also</H2>
<A HREF="../../lib/mode_analyser/result-0.html">result / 0</A>, <A HREF="../../lib/mode_analyser/result-1.html">result / 1</A>, <A HREF="../../lib/mode_analyser/reset-0.html">reset / 0</A>
</BODY></HTML>
